---
layout: docs
page_title: Filtering - Worker Tags
description: |-
  How to use worker tags to control which workers can handle a given resource.
---

# Worker Tags

This page describes how to use worker tags and filters to control which workers
are allowed to handle a given resource. This can be used to control traffic
locality. As an example, this can be used to ensure that traffic going into a
public cloud is only handled by workers running within that same cloud.

Starting in Boundary 0.1.5, a worker can be configured with a set of key/value
tags in its configuration file. The keys and values can be any lower-cased
printable value. Each key can have more than one value:

```hcl
worker {
  name = "web-prod-us-east-1"
  tags {
    region = ["us-east-1"]
    type   = ["prod", "webservers"]
  }
}
```

As HCL is JSON-compatible, this turns into an input JSON value of:

```json
{
  "worker": {
    "name": "web-prod-us-east-1",
    "tags": {
      "region": ["us-east-1"],
      "type": ["prod", "webservers"]
    }
  }
}
```

~> **Note:** This is the canonical format, as it maps closely to the filter
structure. However, for compatibility with some other systems, it is also
possible to specify the tags in a pure key=value style:

```hcl
worker {
  name = "web-prod-us-east-1"
  tags = ["region=us-east-1", "type=prod", "type=webservers"]
}
```

In this format, it is not possible to have an equal sign be a part of the key.

It is also possible to set the entire `tags` block or the keys' values within
to point to an environment variable or filepath in the system, through the
`env://` and `file://` URLs:

```hcl
worker {
  name = "web-prod-us-east-1"
  tags = "env://BOUNDARY_ALL_WORKER_TAGS"
}
```

```hcl
worker {
  name = "web-prod-us-east-1"
  tags {
    type   = "env://BOUNDARY_WORKER_TYPE_TAGS"
    region = "file://config/worker/region_tags"
    usage  = ["admin"]
  }
}
```

Note that the syntax within the environment variable / file changes
slightly depending on how the configuration file is set:

For setting the entire `tags` block, both the keys and values need
to be specified, in JSON or HCL format:

```json
{
  "region": ["us-east-1"],
  "type": ["prod", "webservers"]
}
```

```hcl
region = ["us-east-1"]
type   = ["prod", "webservers"]
```

For setting the keys' values within the `tags` block, only a JSON
array with the tags intended for the particular key is required:

```json
["prod", "webservers"]
```

# Worker filtering

As filters operate on JSON Pointer selectors, the values that are input into the
filter come from the JSON representation of the values in the configuration file
nested under `tags` and include a `name` value:

```json
{
  "name": "web-prod-us-east-1",
  "tags": {
    "region": ["us-east-1"],
    "type": ["prod", "webservers"]
  }
}
```

~> **Note:** If an expression fails due to a key not being found within the input data,
the worker is not included in the final set, so ensure that all workers that
should match a given filter are populated with tags referenced in the filter
string. As a corollary, it is not possible to distinguish between a worker that
is not included due to the expression itself and a worker that did not have
correct tags.

Following are some examples of using these values in filters:

- Name regex: `"/name" matches "web-prod-us-east-[12]"`, which would
  match workers whose names are `web-prod-us-east-1` or `web-prod-us-east-2`

- Region: `"us-east-1" in "/tags/region"`. Note that each tag can have multiple
  values, so it must use the `in` operator to search in the collection. If you
  know that you have only one value, an equivalent would be `"/tags/region/0" == "us-east-1"`.

- Grouping: `("us-east-1" in "/tags/region" and "/name" == "web-prod-us-east-1") or "webservers" in "/tags/type"`

# Target worker filtering

Once workers have tags, you can use these tags to control which
workers are allowed to manage a given session by specifying optional worker filter attributes
when you configure [targets](/boundary/docs/concepts/domain-model/targets).

The `egress_worker_filter` attribute controls which workers are used for egress to a target. This is the worker
that accesses the target.

The `ingress_worker_filter`<sup>HCP Only</sup> attribute controls which workers are used for ingress to a target.
This is the worker a client connects to when initiating a connection to a target.


# Vault worker filtering <sup>HCP only</sup>
Tags are used to control which [PKI workers] can manage Vault requests by specifying
a `worker_filter`attribute when configuring [credential stores].

This allows the use of private Vault instances with Boundary. PKI workers
deployed in the same network as a private Vault instance can access and relay
Vault requests to Boundary controllers.

 ~> **Note:** A PKI worker that matches the worker filter must exist before defining the Vault credential store, as it
 will perform the Vault calls needed to set up the credential store with Boundary.

[PKI workers]: /boundary/docs/configuration/worker/pki-worker
[credential stores]: /boundary/docs/concepts/domain-model/credential-stores#vault-credential-store-attributes
